Turnbull China Bikeride/Turnbull China Bikeride - Disc 1.iso/HENSA/MATHS/PLPLOT/PLPLOT.ZIP/FAQ

Text File | 1994-09-05 | 47.6 KB | 990 lines

PLplot FAQ (Frequently Asked Questions)
---------------------------------------

This note contains answers to some Frequently Asked Questions (FAQ)
regarding PLplot.  There is no particular order of topics at present.

Disclaimer:

The questions & answers that follow typically have been posed (and
answered) to (by) me in email, and seem to me to be worthy of inclusion in
a FAQ.  They may be out of date with respect to the current revision, or
be otherwise suspect (misleading, incomplete, etc.).  Personal opinions
may be contained within: this document is not to be considered the
official opinion of the IFS or University of Texas or any other funding
agency supporting this work.  Feel free to send comments or corrections to
me (Maurice LeBrun) at [e-mail].

Since I like the conventions of the CVS FAQ, I will adopt them here.  Each
question in the table of contents will be given a change marker in the
first column:

    '-'    for a Question that has changed.
    '='    for an Answer that has changed.
    '#'    for an entry with changes to both Question and Answer.
    '+'    for a newly added Question and Answer.

I will feel free to not mark trivial changes (misspellings, grammar, etc).

==============================================================================
Contents
--------

 1. Installing PLplot
 2. General features
 3. X-based drivers (includes Tcl/TK, Tcl-DP)
 4. All other drivers & supported platforms

==============================================================================
Section 1: Installing PLplot

 1.1  How do I build & install PLplot?
=1.2  Where do I install PLplot?
 1.3  Why should I use PLplot?
 1.4  I don't have an ANSI compiliant C compiler.  How do I compile PLplot?
=1.5  I don't have a fortran compiler; how do I compile PLplot?
=1.6  The linker complains of unresolved functions atexit(), fsetpos(),
      fgetpos(), and so on.
 1.7  The compiler complains about the use of "malloc" or "size_t".
 1.8  The compiler complains about "caddr_t" in one of the X support files.
 1.9  configure script doesn't run correctly
#1.10 (removed)
 1.11 The linker complains that it can't resolve Tcl_AppInit.

==============================================================================
Section 2: General features

 2.1  The manual doesn't mention capability...
 2.2  How do I change to change the default background color?
 2.3  I'm getting core dumps when calling a contour function from C.
 2.4  Changing the default line width doesn't have any affect.
 2.5  How can I generate more than 16 line colors?
 2.6  What 2-d array organization am I supposed to use from C?
 2.7  On stretched windows, the string characters look bad..
 2.8  I would like to capture key sequences..
 2.9  How can I get more information about the function/capability..

==============================================================================
Section 3: X-based drivers (includes Tcl/TK, Tcl-DP)

=3.1  Where do I get Tcl/TK or Tcl-DP?
=3.2  How do I use "xauth"?
 3.3  How do I use the Tcl/TK driver?
 3.4  I've been having trouble getting the TK/TCL and PLplot working on...
=3.5  I would like to issue a plot command, have the window appear,...
 3.6  The X driver seems to run slower than on older versions of PLplot.
 3.7  How do I change the title on the TK window menu bar, i.e...
 3.8  I want to run plserver as a daemon...
 3.9  Problems printing from the Tk driver..
 3.10 Problems compiling xwin.c...
+3.11 Problems saving files from the Tk driver.

==============================================================================
Section 4: All other drivers & supported platforms

 4.1  What about support for platform..
 4.2  What about PLplot support for VMS?
 4.3  PLplot is aborting with: Error opening plot data storage file.
 4.4  Is there a Windows port of PLplot?

==============================================================================
Section 1: Installing PLplot
==============================================================================

 1.1  How do I build & install PLplot?

For a Unix-based system, read the file INSTALL in the distribution directory.
Otherwise look at the system-dependent notes under sys/<system name>.


=1.2  Where should I install PLplot?

There are two basic answers to this question: whereever you want, and
whereever I want.

The configure script and Makefile are set up so that you can put the
various components of PLplot virtually anywhere.  By default, it
installs into a directory with the following subdirectories:

bin       doc       examples  include   info      lib       tcl

As for the directory to install into, I recommend on Unix systems a
directory just for PLplot.  On Unix systems, under /usr/local is a good
place.  For one, it's not too difficult to get a system administrator to
give you ownership of a directory somewhere in the public hierarchy.  On a
smaller system, giving the package it's own directory helps maintain
system integrity.  The paradigm of dropping everything under /usr/local
(or even worse, /usr) makes everything simple to install initially but
leads to a system that's difficult to organize and maintain.  There's
the possibility for file name collisions -- stuff that isn't in your
search path but needed anyway (readme, doc, and config files).  There's no
way to cleanly & robustly back out the revision.  There's no way to tell
where each file in /usr/local/bin (lib, etc) came from.

Any sufficiently large/complicated package has this problem.  Dedicating a
directory tree is the only way to preserve the package's integrity.  The
only good reason I've heard so far for NOT doing this (apart from laziness
when installing) is that people then have to modify their search paths,
etc, to use the new package.  Therefore, I've written a script that takes
care of that.  Run docs/mklinks from the install directory, to install
softlinks from the install directory into ../bin, ../lib, ../include, and
../man as appropriate.  Just as important, you can run it again TO
COMPLETELY REMOVE THEM.  Thus it becomes trivial to install and back
down a revision.  All software should work this way.

Note, I've written a similar script for Tcl/TK and extensions, called
"installtk".  A copy is on harbor, but the current version of "mklinks"
distributed with PLplot works with BOTH.  With this I've brought up and
backed out a TK rev on several occasions, and found it immensely useful at
the time, which is why I wrote it :-).  I think it is the most handy in
two cases: 1) when developing using new betas, or 2) in a production
environment, where you want to bring up a new package but still have the
old one available in case programs break.  In the latter case, the only
sensible scheme is to have the package in its own directory.

Now, if after all that you STILL want to break the package up, just set
the appropriate shell variables for the install directories before running
configure, in ~/config/cf_plplot.in (see configure notes).  That way you
can put the docs, examples, and tcl files under $prefix/plplot, and
everything else under $prefix/bin, $prefix/lib, $prefix/include,
$prefix/man (imagine $prefix=/usr or $prefix=/usr/local and this will make
perfect sense).  OK, there are no man pages yet, but there will be one of
these days.


 1.3  Why should I use PLplot?

This is probably the first question I was ever asked, and it continues
to come up often enough to dwell on it a bit.

First off, my involvement with PLplot came from a very simple need: a
portable, free, reasonable quality scientific graphics package.  At the
time I had a 1 year fellowship in Japan, to continue my work on numerical
simulation of plasmas.  Previous to this, I and my colleagues had
laboriously translated the simulation code graphics to use two other
libraries (one quasi-commercial and one PD), only to find both packages
lacking in some important respects (most notably the PD one) and unable to
easily (or cheaply) obtain the commercial one where I was working in
Japan.  This was an extremely frustrating situation, which had always been
apparent to me but only then came to a head.  Scientific graphics is an
utter necessity to anyone doing numerical modeling, and I decided that
being at the mercy of vendors and computer centers on this issue was
unacceptable.

I have no objection to commercial software, but let's face it.. sometimes
commercial solutions suck.  This is one of those times.  You don't have
access to the source code, so you can't improve it to suit your needs
better, and you certainly can't freely carry it to different machines.
Software environments on high-performance Unix systems, especially as
regards commercial software, are VERY variable from machine to machine.
Regardless of why this situation exists, I decided I could no longer
depend on commercial software to provide a basic graphics capability.  I
was somewhat familiar with PLplot for the Amiga, and seeing that it was
fairly capable and portable I decided this would be the "last" graphics
package I would use and support (for a long while at least).

It turned out that PLplot required some substantial investment of my time
before it satisfied all of my (then) needs, but has nonetheless performed
quite well.  In the interim I took over development for it from Tony
Richardson.  The package has become almost trivially portable -- we can
now get our codes running on a new machine in record time.  We can fix
bugs in record time, although it doesn't always happen that way :-).
Still, it takes less than a month or two for me to get around to fixing
most bugs, which is better turnaround time than you typically get from
vendors.  New features can be added with astonishing speed if the need
(ours) is great enough.

So those are some of the reasons /I/ got involved, which may differ from
those of the casual user.  Most people won't be digging into the source
code to fix bugs, but it's very reassuring to know that you can if you
need to.  I can't promise to support the package or make specific
enhancements as my responsibilities (i.e. funding) lie elsewhere.  But I
am always interested to hear what people want, since if it's a good idea I
will benefit too.  User-contributed code is always welcomed (I have had
quite a few).  And backward incompatibilities will be introduced into
the package sparingly if at all.

The features supported by PLplot are necessarily fewer in number than a
big commercial package.  PLplot has a fairly complete set of basic
graphical capabilities, and a few very strong capabilities (e.g.  the
Tcl/TK X-based GUI driver or its sibling the DP driver, the latter of
which supports distributed rendering).  This has its good and bad points.
The good part is that the library is relatively small, and can be modified
without too much difficulty.  The disk space required is reasonable
(especially if shared libraries are used), and the learning curve mild.
The effort I might expend adhering to some large set of capabilities (many
of which may be only rarely used; e.g. look at the GKS standard) can be
focused instead on portability, user interface, and certain select
capabilities.

On the other hand, there are many nice capabilities missing from PLplot at
present, such as support for solid 3d modeling, postscript fonts, and so
on.  New features are continually being added, but the fact remains that
other more special purpose (and/or high priced) products will always have
things that PLplot lacks (or do them better).  One way I see to fit PLplot
in the overall software environment is to add more output drivers, both
for generic file formats (e.g. GIF, CGM) as well as for specific graphics
packages (e.g. AVS).  That way you could produce your graphics and view
them using PLplot, dumping to disk those pages or plots you want to
process using a separate package.  This can already be done using the XFig
driver, for example.  For this to be most effective, PLplot should have
internal knowlege of more varied objects than "line" (currently the
fundamental unit), and I have some plans in this area.

I'm always interested in gaining new collaborators and contributors for
PLplot, so feel free to send me email ([e-mail]) so we can
discuss additions you'd like to make.  Want to help support PLplot but
need suggestions?  I hesitate to recommend anything that will require
broad changes to the package, but any of the following would be great:

    volunteers for target platform support (I have HPUX covered)
    output drivers: GIF, CGM, others?
    PLplot demos?  (especially using Tcl/TK)
    an improved contour plotter
    any interesting ideas/code for TK widgets for use with PLplot
    anything from the ToDo list you'd like to tackle?
    help rewriting the manual?  (OK, so I'm really reaching here)


 1.4  I don't have an ANSI compiliant C compiler.  How do I compile PLplot?

Get an ANSI C compiler.  The cheap solution is to get gcc up if it has
been ported to your machine.  This is not unreasonable IMHO -- the C
standard was approved in 1989.  Isn't it about time you upgraded?


=1.5  I don't have a fortran compiler; how do I compile PLplot?

The Fortran files are only part of the interface layer for Fortran codes
that use PLplot.  If you don't need this capability the layer can be
omitted by running configure with the --disable-f77 flag under Unix.

Alternately, you can use 'f2c' (freeware fortran-to-C translator) to
compile the layer, assuming it (f2c) has been ported to your system.


=1.6  The linker complains of unresolved functions atexit(), fsetpos(),
      fgetpos(), and so on.

This is caused by a non-ANSI libc.  It /is/ possible to run PLplot on such
a system, but at slightly reduced functionality -- I rely on ANSI libc
functions both for seeking (fsetpos, fgetpos) and for cleanup (atexit),
but neither is absolutely essential.  Currently the configure script
should detect this condition automatically and make the necessary defines
to avoid any problem.  If not, let me know and I will fix it.


 1.7  The compiler complains about the use of "malloc" or "size_t".

Once upon a time, the source code went to some lengths to make sure
these were properly prototyped/typedef'ed even on systems that weren't
completely ANSI-compliant.  Now the code assumes they are in the usual
places:

    malloc    should be declared in stdlib.h
    size_t    should be typedef'ed in stdio.h (sometimes is in stdlib.h
        also, and sometimes only in stdlib.h.  The latter is a
        violation of the standard but I look for it there too.)

So when these are needed, stdio.h and/or stdlib.h are included.  If
this does not work on your system, there are two things to try.  First:
fix the headers.  You can leave the current definition in place as
long as you "wrap" it, e.g.:

#  ifndef _SIZE_T
#    define _SIZE_T
     typedef unsigned int size_t;
#  endif /* _SIZE_T */

Then add an identical declaration where it is *supposed* to be.  The
second way is to hack plplot.h to explicitly prototype/typedef it.


 1.8  The compiler complains about "caddr_t" in one of the X support files.

This is sometimes seen on systems that have X11R4 and claim POSIX
conformance but that don't quite have their act together.  Typically on
old versions of Unicos, Ultrix, and DGUX for example.  Currently the
configure script determines whether caddr_t is typedef'ed, and if not,
defines caddr_t appropriately.  Note that under POSIX.1, caddr_t is
NOT supposed to be set.  But because of the various broken headers out
there I compensate by defining it except when it is (illegally) already
typedef'ed.  In any case, it should always work, and if not let me know.


 1.9  configure script doesn't run correctly

The current configure script should work under even some very old versions
of "sh".  But in the event of problems, look around for a different shell
to run it under (posix shell, ksh, /bin/sh5, etc).

Be sure to check that the system name is being set correctly.  Your system
must have the "uname" program.  If not, you can roll your own easily
enough -- here's one for HPUX:

--cut-here--cut-here--cut-here--cut-here--cut-here--cut-here--cut-here-
#!/bin/sh
#
#       File: uname
#       Usage: uname
#
#       Minimal implementation of the uname command -- no arguments
#       supported.
#
echo "HP-UX"
--cut-here--cut-here--cut-here--cut-here--cut-here--cut-here--cut-here-

Alternately, you can explicitly set "system" either as a shell variable or
in the defaults file.


=1.10  (removed)


 1.11 The linker complains that it can't resolve Tcl_AppInit.

The Tcl7.0/TK3.3 and later libraries contain a function called "main".
As a result, when linking you don't always get the correct main program.

This was done to make it easier to build custom versions of wish, so
all you had to do is to create your own version of Tcl_AppInit, link
with the library, and POOF! there is your modified wish.  Unfortunately
it sometimes sends the fortran compiler / linker into spasms, because
it gets the wrong main!  I have had exactly this problem under a 2-year
old version of SunOS (but not under a more recent one), and couldn't
get it to work despite varied link invocations.  BTW, I hear a similar
problem exists under Linux from a C++ main.

My solution on these platforms was to recompile the tcl and tk libraries
without the file including the main program (I think it was tclMain.o and
tkMain.o).  I installed the new libraries as well as the separately compiled
*Main.o's in case someone needed them.  No more problem with the Fortran
compiler.

Another case where this may come up is using f2c to compile a Fortran
main, in which case the true main is in libf2c.a.  In this case, putting
-lf2c BEFORE -ltk -ltcl on the link line will usually do the trick.

==============================================================================
Section 2: General features
==============================================================================

 2.1  The manual doesn't mention capability..

The manual is waaay out of date.  Consult the last few update files to
keep tabs of what's going on.  Take a look if there are are any
substantial new capabilities in the example programs.  We went wild on the
manual a while back, rewriting it in LaTeXinfo so that we could publish it
in info file form.  That info file is available in the doc directory, but
unfortunately (a) it still needs some polish and (b) it is still waaay out
of date.  The next big push will see the end of it.


 2.2  How do I change to change the default background color?

Use the -bg option.  Type plrender -h.


 2.3  I'm getting core dumps when calling a contour function from C.

Aha.  Did you specify the minimum index as 1, not 0?  This is a leftover
from when the package was written in Fortran, sigh.  I'm not sure why this
isn't explained in the manual -- I just looked and there is no mention of
it.  When I first got involved I mainly learned how to use the package
from the demo programs and so didn't really notice the inconsistency.
I've added some more explanatory error messages and will improve the
document in this area.  Unfortunately it may be too late I think to change
the minimum index to 0, since by now many people are used to this way.
Maybe add some new function calls to fix up the API..


 2.4  Changing the default line width doesn't have any effect.

Not all drivers support multiple line widths, in particular,
pixel-oriented ones such as all the Tek drivers.  Further, it may not even
mean the same thing from driver to driver.  If this ever becomes a serious
enough inconvenience I may take a harder look at it.  One problem is that
display devices typically don't have the resolution for resolving the
difference between different line widths.  For example, you can output
a plot using different line widths to a postscript file, and the lines
don't appear any visibly thicker until you hit 5 or so (so 1-4 look the
same, same for 5-8, and 9-10, or something like that).  The only real
way to see the difference is to print it.  Another problem is that there
may be no device support for multiple line widths.  In this case you
can mock it up by drawing lines multiple times (very close together),
but this is a real pain.

The driver does initialize the width to something reasonable, but only
if the user hasn't already set it (i.e. it is zero).  The postscript
driver uses a line width of 3 as a default, since this produces pretty
good results.


 2.5  How can I generate more than 16 line colors?

You can use cmap1 to do it, via plcol1().  Each color will be interpolated
along a piecewise linear curve in HLS space.  Eventually I will allow
the user to ask for arbitrarily large palettes in cmap0 too, but it's
not a high priority, since the smooth color variation supported by cmap1
is often excellently suited to the task.


 2.6  What 2-d array organization am I supposed to use from C?

The 2d array organization has an interesting history.  Back in plplot 2.6b
all the C API functions that took 2d arrays used column dominant
contiguous storage, while the corresponding Fortran API functions used row
dominant contiguous storage (naturally).  The latter allocated temporary
arrays and performed a transpose before calling the C API.  With plplot
3.0 Tony Richardson changed the C API to use arrays-of-arrays of pointers
to increase performance on some platforms.  Unfortunately on high end
platforms (vector machines or superscalar RISC workstations) performance
can actually be worse as a result -- slowdowns due to memory access can be
much worse than doing extra computation.

As a result the situation re: 2d array organization in C became somewhat
confusing -- now there was a /third/ type of array organization, or /four/
if you want to count "normal" C array-of-pointers organization.  So I
decided, years ago, that I wanted to have a general way of specifying
array organization to be used by the 2d function API, with front-end
routines used for converting from popular techniques.  But as it isn't so
glamorous a pursuit, I've been slow to get it finished. :-\

The key idea is that for each major capability, there should exist a core
function that takes the array in a totally arbitrary way -- as a function
evaluator and its data.  This can be used directly if desired -- for
example by a C++ user with his own matrix class.  However I also will
provide front-end C API calls to handle the various popular 2d array
organizations.  These front-ends merely pass in the appropriate function
evaluator to the core routine, passing the user's array as data.  This
results in calls like plfcont(), which is the core routine, and plcont1(),
plcont2(), etc, which are the front-end routines.

The core routine can do one of two things: it can either use function
evaluations in place of the 2d array lookups in its computations, or
create a temporary array in some standard internal format for its
computations.  Both have their merits.  On low-end machines, the function
evaluator approach is better (since there is little loss of pipelining and
no temporary memory hit), while on high-end machines the reverse is true.
On the other hand, on high-end machines the odds are better that you are
spending most of the CPU time on things other than graphics, and
efficiency is less important.  So I tend toward using the function
evaluator where it is convenient.  In the contour plotter the function
acceses are clear and it was easy to substitute a function evaluator.  In
plshade, however, the code is a bit too involved for this to be done
easily so instead I've gone the temporary array route.  Either way, as
long as the API is put in place and documented, I can always go back and
change things around internally later on.

My intentions right now is to give this a good look very soon, so that
if I need to break the C API to make it more consistent, it happens
before I release 5.0.


 2.7  On stretched windows, the string characters look bad..

> - If I make a window of say y=100 and x=1000 the character are rather
>   stretched. Is there a way to avoid this.

I haven't had the need for it and am barely familiar with how to do it.
The best way to fix it won't happen until I support actual text by the
driver, which is a long ways off yet.  But I think you can specify
physical dimensions of your output device using plspage().  In fact,
plspage() is called by the argument parser for the -geometry flag, but the
options specifying physical dimensions -- xpmm and ypmm -- aren't filled
in.  I can put changing this on my todo list.  But if it works, it will
only work as long as the window isn't resized.

Eventually, the driver and internal page representation will be
intelligent enough to support page resizing without changing the aspect
ratios of certain objects such as characters, strings, fixed aspect
viewports, etc.  But like I said, it's a way off.


 2.8  I would like to capture key sequences..

>   Also, I would like to be able to capture the PF2 and PF4 keys. My
>   application consistently uses these keys for particular responses. If
>   I can catch them, the application can take appropriate action.

You can catch these now from C by installing a keyboard event handler,
via the function:

/* Set the function pointer for the keyboard event handler */

void
plsKeyEH(void (*KeyEH) (PLKey *, void *, int *), void *KeyEH_data);

You can look at the code in plrender as an example.  It uses a keyboard
event handler in order to detect & act on page seeking commands.  It would
be possible to mock something up for Fortran too if needed.  There is no
problem with doing this from X since only a single key code is
transmitted, but an xterm sends an escape sequence.  Your event handler
would be called for each key code which makes recognition a bit harder but
still doable (if in an xterm).  Let me know if this helps.


 2.9  How can I get more information about the function/capability..

> I would like to be able to take advantage of the new routines that came
> with 4.99g, but to do this I need to know the argument list that is
> supplied to each one - the additional docs that came with 4.99g are very
> sketchy on this.
>
> I would particularly like to use plscmap1l, which I have had trouble
> with,  also the following which are not explained:
>
>  *      plwarn plexit plcol0 plcol1 plrgb plrgb1 plscolbg plscol0 plgcol0
>  *      plscmap1 plscmap1f1 plscolor
>
> Any details would be gratefully received.

Well for me to really explain would be basically the same as finishing the
docs, which I don't have time for right now.  I suggest looking at the
example programs and especially the source.  Now, I know that might not
sound like fun, but some of the source code is a fairly easy read.  Look
in "plplot.h" -- each function has a prototype that lists arguments and
has a one-line description.  The description is usually an abbreviated
version of the comments written with the function itself.

If you are an emacs user, browsing the source code is very easy with
'tags'.  From the tmp directory, type 'etags *.c'.  Then edit plplot.h,
move the cursor to the name of the function you are interested in, and
type ESC-.  <poof>, you are there.  Happy hunting.

p.s. Some of the new capabilities are illustrated in C example programs
but not Fortran, e.g. see x15c and x16c.  x17c isn't working yet.


==============================================================================
Section 3: X-based drivers (includes Tcl/TK, Tcl-DP)
==============================================================================

=3.1  Where do I get Tcl/TK or Tcl-DP?

You can get the Tcl/TK package by anonymous ftp from sprite.berkeley.edu
in the tcl subdirectory (or from harbor.ecn.purdue.edu in directory
pub/tcl).  Also consult with the comp.lang.tcl newsgroup on Usenet.
Tcl-DP can be obtained by anonymous ftp from mm-ftp.cs.berkeley.edu in
pub/multimedia/Tcl-DP, and is highly recommended.  At the time of this
writing, the versions that are fairly certain to work with PLplot are:

tcl7.3
tk3.6
tcl-dp3.1
tcl-dp3.2 (has been tested under HPUX)

Earlier versions may be iffy.

Note: the Tcl/TK, Tcl-DP header files should be found automatically by the
configure script if they are in a relatively predictable location.  Many
locations are checked; see cf/sysloc.in for more info.  If they aren't
found on your system, consider: (a) moving them, (b) making softlinks to
one of the searched-for locations, (c) if you REALLY think your location
should be searched for automatically, feel free to ask me to change it.


=3.2  How do I use "xauth"?

The 7.0/3.3 and later releases of Tcl/TK require xauth security in order
to accept send requests.  The only problem is that you have to
*completely* eliminate use of the older xhost method.  So typing "xhost -"
isn't good enough -- you must also explicitly delete all the names from
the xhost access list (type just "xhost" to see them).  That should do it
for your local node.  To grant remote nodes access, just ftp your
~/.Xauthority file (server machine) to your remote home directory.  There
are some notes on setting this up in the file Xauthority in the doc
directory.

I know from experience that setting up and using xauth security can be
a major pain in the neck.  For example, a site that's basically secure
can be configured by the system manager to enable xhost access to all
local nodes automatically through the /etc/X0.hosts file.  At such sites
the users are unaccustomed to explicitly granting permission and on a
secure group of machines there's no real security risk.  HOWEVER, a user
may need to occasionally access an "outside" machine, and since you can't
mix xhost and xauth, you are hosed.  And compiling TK without xauth
security is a gargantuan, tremendous security hazard.  A sickeningly vile,
disgusting mess.

Therefore I recommend that if you have any concerns about security or
problems with TK send, and ESPECIALLY if you are running from some remote
host, just forget about the TK driver altogether and use the DP driver
instead.  The DP driver uses a much superior method of communication
(sockets rather than X properties) and is distributable to boot.  It does
have a slightly longer startup time.  If you are running on a machine off
the network (where maybe you don't have a full TCP/IP implementation) the
TK driver is fine.  The DP driver only allows open connects between the
time it takes to launch the server and they do their initial handshaking,
a hole that I view as impossible to take advantage of.


 3.3  How do I use the Tcl/TK driver?

Get it going with the example programs, and play with it.  Read the online
docs.


 3.4  I've been having trouble getting the TK/TCL and PLplot working on
my Indigo running IRIX 4.0.5. I got TCL7.0 and TK3.3 as advised and built the
libraries and moved them to "/usr/lib" directory and then went about
(re)building PLplot. I then compiled the c-demos and ran them. The tk driver
would pop up a window and disappear with the following complaints...
...
>>Starting up ./plserver
>>Server command "[list $plw_init $plwindow $client]" failed:
>>         remote interpreter did not respond
>>Program aborted

I think what is happening is that plserver is dumping core for some
reason.  So why don't you get a "core dumped" message?  It has something
to do with it being created through fork/exec from the TK driver.  Never
quite knew what, but now that I am thinking about it once again I bet I
know what the deal is.  It takes a little bit of time for it to dump core,
and in that time the sending interpreter in the TK driver times out, and
aborts.  Since the application is the parent process, once it exits you
don't see any pending messages that the plserver (child) has.  In this
circumstance I'm not sure if one should always get a core file or not.

So, the key is to find out why plserver is dumping core.  There are
a few things you can do.  When you built Tcl/TK, did you run the tests?
You need to type "make test" in either the tk3.3 or tcl7.0 directory, and
it will merrily go on its way.  After you have done that, try cd'ing to
the tk3.3/tests directory and running the tests using your installed
version of wish.  Some of the tests will fail because "make test" actually
compiles a custom version of wish with some extra functionality just for
the test suite.  But most of the tests will do ok.  If not, you hosed
the installation and that would explain the observed behavior.  If not
we need to do some more hunting.

Here are some more things to try: define DEBUG at the head of the files:

    plserver.c    (will give you information at startup)
    tk.c        (this does the launching of plserver)

This should tell you at the very least if plserver is getting started
correctly.  In addition, to get a whole LOT of output about the current
state of the code, you can define also DEBUG_ENTER in:

    plserver.c
    tk.c

and even:
    plframe.c (also define DEBUG here, but be ready for lots of output)

The resulting messages often prove useful.


=3.5  I would like to issue a plot command, have the window appear,
or be re-painted, and allow the user to continue with command line operation
of RLaB. I would like the user to be able to resize the window at any time
or cover/un-cover it at any time and have it re-paint itself. The way  I
can get it to work is: the user issues plot command, window appears and is
resizable, etc... the user must use the 3rd mouse button to "release" the
window, after that control returns to the command line, but the window will
no longer resize/repaint.

This is a feature, not a bug :-).

When the plotting package is waiting for the user to advance the page, it
is actually waiting for any X event.  So events like refresh and resize
get intercepted and processed.

Also during the normal course of plotting, the X server is periodically
polled to find out if there are any events that need processing, and
handles them if so.  I don't do this on every graphics instruction because
otherwise the overhead is too large -- currently on every 20 line draws,
every 10 polyline draws, and on every other call.

But once the user signals for the page advance, and control is returned to
the user program, there is no way for the X driver to process any events
simply because the control is in your program, not in the X driver.  The
single-headedness of your process becomes the culprit here.  You can
either sit in an event loop, or be doing user code specific things, but
not both.  If you want to periodically tell the driver to handle pending
events, there is an escape function call for that, but it's really just a
bandaid solution.

The best solution is to fork off the rendering into a separate process,
and this is just what I did with the Tcl/TK driver.  So, if you select
the tk driver, your code can go about its merry way while the graphics
window can be refreshed, resized, zoomed, printed, dumped, or whatever.

It'd also be a worthwhile project to split the X driver similarly, and
there has been some interest in doing that (but I don't plan to work on
it).


 3.6  The X driver seems to run slower than on older versions of PLplot.

This may be caused by writing into the pixmap.  Each instruction is
essentially done twice -- once to the screen and once to the offscreen
pixmap.  I'm not happy about the tradeoff but there's not much that can be
done.  With the pixmap, you get fast refreshes but slow draws, and the
other way around without it.  What made me decide on using a pixmap as the
default is the smooth scrolling that you can get (try a zoom followed by a
scroll in the TK driver -- without writing into a pixmap the scrolling
really sucks).  One way would be to write only to the pixmap and
occasionally blit it to the screen, but that would be jerky and you'd have
to worry about incomplete pages.  Try plotting with the -nopixmap option
to see if that's any better.  I do almost all my PLplot X development on
an HP 720 color console and graphics speed is usually not a problem :-).


 3.7  How do I change the title on the TK window menu bar, i.e.,

>   Plot >> plclient_#2
>
>            ^^^^
>            I'd like this to read SuperCode

It uses the name of the main window if nothing else is set.  You can set
it two ways.  One, use plParseOpts to parse your command line, then it
will use argv[0] out of that list.  Two, just glom pls->program directly,
via:

#include <plstream.h>

PLStream *pls;

...

    plgpls(&pls);
    pls->program = "myprogram";

Yes, by this method you have access to the complete internal state of
the current PLplot stream.  So be careful what you change :-).

There is one catch, though.  The way it is set up now it must be a unique
name since it corresponds to your main window name (to which X property
messages are sent).  If there is a previous Tcl interpreter of that name
hanging around (say, as a result of some sort of abnormal exit like a core
dump) you will get the mysterious _#2 appended (and _#3, and so on; note
there are utilities [zapinterps or delinterp] that will delete these zombie
interpreters).

 3.8  I want to run plserver as a daemon...

> What would be really desirable, would be to make plserver into an
> actual daemon, as described in Stevens UNP.  Very cool idea, how
> daemons work.  The plan would be to have a guy sitting there
> monitoring a port/pipe/whatever, and when a connection request comes
> in, he forks, and calls back to the app with directives to use a new,
> previously unused (or reclaimed) port.  Then the daemon goes back to
> listening.  That way, you could run multiple apps simultaneously, each
> getting a new plserver if a spare one isn't already available...
>
> I think the default action would be that when you punch >> on the last
> plot, the client goes ahead and terminates, but plserver stays up, for
> future invocations.  But when the user wants to get rid of it, if he
> doesn't plan to plot for a while, then there's a kill/off button
> somewhere on the pannel.

Actually it is possible now to start up a plserver and connect to it,
using the DP driver.  But one of the problems with this is the security
issue.  I get around the problem now by only allowing connects during
the brief time between the fork/exec and when the connection succeeds.
If it was open for longer we run into the same old possibility for
nasty interpreter commands being sent.  Dunno if there's a good way
around this.


 3.9  Problems printing from the Tk driver..

> We're having some big problems with the latest release of PLPLOT.
> Basically, we can't print and we can't save Postscript files. When we
> try to print we get
>
> *** PLPLOT ERROR ***
> process_next: Unrecognized command
> Program aborted
> lpr: standard input: empty input file

Interesting.  Sounds like maybe an incompatibility with the plplot library
output and plrender [note: turns out it was indeed a previous version of
plrender in the user's search path].  The 'print' command saves the page
as a plplot metafile, and then invokes plrender to turn it into
postscript.  Either it was installed incorrectly, or (more likely), it is
a bug.  I have printed plots by this method without problem since the
4.99g release, but probably I didn't exercise everything.  Maybe try "Save
As.." with a variety of file types and see if anything turns out.

> I have my PRINTER environment variable set. Am I supposed to do
> something else?  As for saving Postscript files, it seems to write part
> of the file and then just stop in the middle. It appears that some
> buffer is not getting flushed.  Any ideas?

Take a look at the plpr script, it is braindead, but I never had much time
to embellish it.  It doesn't allow you to set a particular printer, which
I guess is what you want.  You can always edit the file, for site-wise
customization.  Of course, this sucks, but is the best I have for now.
Isn't "lpr" supposed to obey the setting of PRINTER?  Even if so/not,
there's the question of how to render the saved metafile.  I use mono ps,
since that's usually what people want.  But sometimes I've wanted to print
grayscale output, and hit print without thinking, and got a nice,
completely black, plot. :-) So not only do I have to provide for a way to
select this in the GUI but also a way to read customized settings
automatically at startup.  Which brings up init file issues.. (see the
ToDo file).

So for now just modify plpr to your tastes and stick it in your path :-).
It should be located BEFORE the installed copy of plpr, which should just
be the site-wise default.  I usually have ~/bin before most significant
directories in my path anyway.  The exec() call used to invoke it does use
your path I believe.  And if you embellish it significantly, feel free to
send me a copy.


 3.10 Problems compiling xwin.c...

> I am trying to install PLPLOT on a DECstation 5000/240 running Ultrix
> 4.2a and an earlier version of X11R4. I am using gcc with the -ansi
> option.  Running make gives me the following errors:
>
> In file included from xwin.c:50:
> /usr/local/lib/gcc-lib/decstation-ultrix4.2a/2.4.5/include/X11/Xlib.h:3958: parse error before `XSizeHints'

After poking around some on this system I found out that the header files
were hosed.  This is the kind of thing that crops up only when using an
ANSI compiler or C++ since it's in the function prototypes.  In
particular, Xlib.h uses XSizeHints before it's defined (in Xutil.h).  In
the X11R5 header files from HP-UX, all of the functions needing to
reference a variable of type XSizeHints* are prototyped in Xutil.h, after
the declaration of XSizeHints.

I don't know how many systems I've seen with broken X11R4 header files --
a lot.  Seems the X11R4 distribution was partly to blame, but you'd think
the vendor would have at least checked to see whether an ANSI C compiler
would work with them.  In any case, there /should/ be an upgrade to fix
problems like this.  At worst, you can pull over a later X11 distribution
(as I write this X11R6 just came out) and build it yourself.  I do know
that some PLplot runs OK on some Ultrix systems so there should be an
upgrade available.


+3.11 Problems saving files from the Tk driver.

> When I tried to save
> the .ps files (both color and mono) using "Save as.." in plrender,
> it doesn't seem to terminate the file properly. I had to add a
> "showpage" statement at the end before I send it to the printer
> in order for my printer to print it properly. On the other hand, if
> I select the drivers (ps or psc) at the command line or upon start
> of the program, the output files looked fine.

You either need to quit the program or pick "save close" before displaying
the saved file.  This is because "save as" leaves the file open so that
you can use "save" on multiple plots, each going to the same file.



==============================================================================
Section 4: All other drivers & supported platforms
==============================================================================

 4.1  What about support for platform..

Right now the package is most likely to be up-to-date under HP-UX and
Linux, since those are the two systems used most extensively by Maurice
and Geoff.  However we also use SunOS, AIX, UNICOS, and SUPER-UX enough
that probably there will be no problems on those systems also.  The DOS
and OS/2 support is being done mostly by other parties at this point (see
the README).  Any other systems are suspect.  Other Unix variants (IRIX,
OSF/1) are reasonably safe since the PLplot configure script is fairly
sophisticated and portable -- system dependencies tend to drop out without
notice.  I can't make any promises as to the Amiga support since I rarely
compile PLplot there these days.  Also no one is currently supporting the
NeXT.  As always, I'm looking for volunteers to help pick up the slack on
these systems (really, any other than say HPUX and Linux).  At the minimum
this means getting pre-beta releases and testing them, submitting any
fixes that need to be made, that's it!  If you have more ambitious plans
for supporting a particular platform, that'd be great -- let me know.


 4.2  What about PLplot support for VMS?

It's true, I did support PLplot under VMS at one time, although I never
DID see the X driver running on it (supposedly it did).  However after
exclusively using a fast Unix workstation for a while I vowed never to go
back to VMS :-).  The VMS PLplot port caused me lots of pain to get up,
but at least I learned a few things about portability.  Anyway, there may
still be people out there who would find it useful under VMS, so if anyone
succeeds in making PLplot work and want to continue supporting it there,
the job is yours for the asking.  I don't have the time or patience for
it.


 4.3  PLplot is aborting with: Error opening plot data storage file.

The most common reason I've seen for this is that the temporary file area
is set up incorrectly (wrong permissions).  Note: this directory is where
tmpfile() opens its temporaries, which may NOT be /tmp.  You can find the
true location typically by looking in stdio.h.  For example, on my HP
in stdio.h there is:

#  define _P_tmpdir "/usr/tmp/"

look for something similar on your machine, and make sure the directory
has the appropriate permissions (it should have global write set).


 4.4  Is there a Windows port of PLplot?

Look under sys/dos/bcc, there you'll see a file win3.c, which is a Windows
port by Paul Casteels.  I don't know much about it having never tried it,
but have heard some good comments about it.  One nice enhancement is the
ability to print the current plot.


 4.5  I'd like to develop a windowed interface to PLplot for..

For the systems that I've used, developing windowed interfaces is a fair
amount of work.  Most of my experience developing graphical interfaces is
under Unix (and a little on the Amiga).  Unix/X/Tcl/Tk on a fast
workstation makes for an excellent starting point -- it is powerful, and
the final product is fairly portable.  Virtually all my professional work
is on Unix machines, which also drives my effort -- the Tk driver is where
most of my attention has been going.  But it's still a /lot/ of work.

Of course there are still many reasons for using or developing on a
microcomputer -- if I used my Amiga more I'd be more inclined to spend
more time improving the interface there.  As it was, the Amiga had the
first PLplot windowed interface, and it gave me many ideas about how to
proceed with the Tk one.  Unfortunately, too many of these features were
built into the Amiga screen driver instead of the core, and didn't help
directly when I was doing the Tk driver.  So when I improved the package
in order to support the Tk driver I tried to make changes where they could
potentially benefit other windowing drivers.  This should help developers
of other windowed drivers some.

I originally started developing a Motif-based driver, but abandoned the
effort when I saw how much easier Tk-based ones are to construct (and Tk
is free to boot).  At this point I'm very happy with Tcl/TK and am
probably finished with Motif.  There are still some reasons for going with
Motif -- such as needing a specific Motif widget or to satisfy company
policy, market demand, or whatever.  Also the recent development of
interpretive Motif environments that rival Tcl/TK in their ease of use and
prototyping speed (or so I've heard) makes Motif-based GUI construction
more palatable.  If you just want Motif widgets inside your app, you can
do this in Tk (see the comp.lang.tcl FAQ for more info).  Right now there
is no way to do the reverse as far as I know -- include Tk widgets inside
a Motif app, but maybe eventually there will be a way (I mention this
because the development of the plframe widget was the most time-consuming
single thing I've done as regards PLplot).

Under Windows, try the driver by Paul Casteels (see FAQ 4.4).  At the time
of this writing it is still somewhat sparse, but as per the comments above
it may not be unreasonable to extend it in the same directions as the Tk
driver.  Another alternative is to actually use Tk -- there are several
ports of Tk to Windows in various stages of completion.  I'd like to hear
about people's experiences with these, especially with PLplot.

I've been asked several times about a Mac interface.  There was supposedly
a port of PLplot to the Mac some time back, but I never even saw it.  I
don't know beans about programming the Mac, so if some one /else/ wants
to investigate and let me know the status I will include it here.


==============================================================================